Repository navigation
feat: typed capability sources with validation, approval and typed answers - #6
Merged
Merged
Conversation
…d answers Capabilities now come from any source that produces a codemode.Source: typed Go functions (capability/gosource), protobuf (registry) or MCP tools (capability/mcpsource), combined with codemode.Combine. - Validate every capability call against its input shape before ExecuteFunc runs; errors name the path and go back to the repair loop. - gosource.Func derives the schema from Go structs, decodes and encodes, and takes access as a required argument. - agent.RunAs[T] checks and decodes the program's answer into T. - NeedsApproval holds a write and every later one; agent.PlanStore and ApplyPlan apply a plan once, by ID, for its owner. - TypeSchema gains Required and an integer kind.
app.Source builds the three todo capabilities with gosource; the proto path stays behind -source proto, and a test asserts both give the same answer. todo-mcp uses the Go source.
The quickstart builds capabilities from Go structs, returns a typed answer and approves a write. The protobuf quickstart moves to docs/content/protobuf.md. Adds ADR 0008 and the pluggable-sources milestone.
todos.delete is NeedsApproval in both the Go source and todo.proto. todo-mcp builds its server in newServer, and a test shows run_program refusing a program that reaches the delete and naming what did not run.
… chat
The 23 capabilities are typed methods on app.App, served by gosource
by default; -source proto keeps the protos, routed to the same methods,
and a test holds both to the same names, descriptions, roles, reads and
approvals.
tasks.delete needs approval. A chat that reaches it returns the held
plan, the page shows Approve and Reject, and POST /api/plans/{id}/approve
or /reject applies or discards it once, for its owner. A delete from the
board is its own approval.
examples/shop is the quickstart as a runnable, tested example: Go-struct capabilities, a typed answer with RunAs, and a refund approved at the terminal. examples/combined runs one program over a Go function, the todo proto service and an in-process MCP server via codemode.Combine. Both run with no API key (make demo-shop, make demo-combined).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Protobuf read as the core of codemode, so every integration meant buf config, a vendored
codemode.proto, and then a hand-writtenswitch rpcwith request structs duplicating the schema and their own JSON decoding. Nothing validated a program's arguments before the handler ran, approval was all-or-nothing (Options.Plan), and the answer came back asany.The core never depended on protobuf (
capability,codemode,agent,llm,sandbox,programimport neither protobuf norregistry/), so the fix is a developer-facing layer, not a rewrite. ADR 0008 records the decision, including why BAML is not the core.Solution
codemode.Source{Registry, Execute}is what every adapter produces:capability/gosource(typed Go functions),registry(protobuf),capability/mcpsource(MCP tools).codemode.Combineserves several as one, and duplicate names or RPCs are an error.codemode.FromSourcenarrows to the caller and defaults to keyword search.ExecuteFuncruns: unknown fields, kinds, enums, required fields and oneofs. Errors name the path (items[2].id: want integer, got "2") and go back to the repair loop. A rejected call is not recorded, so it never counts as a write.encoding/json, withdesctags andcapability.Enumstring types. Access is a required argument with no zero value. Nil slices are sent as[], and a panic in a handler becomes an error.agent.RunAs[T]tells the modelT's shape, then checks the return value and decodes it intoT. A mismatch is repaired like any other failure.NeedsApprovalcomes fromgosource.NeedsApproval()or the new(codemode.needs_approval)proto option. It holds that write and every later one, and the run returns*agent.Pending.agent.PlanStore,NewMemoryPlansandApplyPlanapply a plan once, by ID, for its owner. Outsideagent.Run, such a write fails instead of running.mcpserverreports held writes instead of claiming success.TypeSchema.Requiredand anintegerkind.capability/jsonschemais extracted frommcpsource.codemode/sourcetest.Runis a contract test that every source runs.-source proto. Docs add a Go-structs quickstart plus pages on sources, types and validation, and approving writes. The protobuf quickstart moves toprotobuf.md.Examples
examples/taskreportnow serves its 23 capabilities from typed Go functions by default, and-source protokeeps the protos. Both paths run on the same typed methods, and a test checks the two declare the same names, descriptions, roles, reads and approvals.tasks.deleteneeds approval: the chat shows the held writes with Approve and Reject, backed byPOST /api/plans/{id}/approveand/reject. A delete from the task board counts as its own approval and runs at once.examples/shopis the quickstart as a runnable, tested example: Go-struct capabilities, a typed answer withRunAs[Revenue], and a refund approved at the terminal (make demo-shop).examples/combinedruns one program over a Go function, the todo proto service and an in-process MCP server throughcodemode.Combine(make demo-combined).examples/todohas atodos.deletethat needs approval, and a test showstodo-mcp'srun_programrefusing it and naming the writes that did not run.Behaviour changes
ExecuteFunc. Hand-built capabilities with no inputFieldsare not checked.mcpsourcemapsintegertointeger, recordsrequired, and falls back to a tool's title or name when it has no description.agent.Applyruns writes that need approval: applying is the approval.Verification
make test: buf lint,go test ./..., the env check, and the consumer check (new packages build withCGO_ENABLED=0and link nothing third-party).go test -raceoncapability/...,codemode/...,agent,mcpserverandexamples/todo/....capability.Validate.make generateafter adding the proto option.pnpm run buildfor the docs (no dead links).go run ./examples/todoand-source protogive the same answer offline.main.gocompiled and ran offline as a separate module.go run ./examples/shopandgo run ./examples/combinedrun offline.pnpm build). Server tests cover holding, approving, rejecting and applying-only-once on both sources. The new buttons were not clicked in a browser, since that needs a live model.Not in this PR
Tagging
v0.1.0, proto typed dispatch,apply_planover MCP, per-caller identity inmcpsource, and the BAML spike. All are tracked innotes/milestones/2026-11-pluggable-sources.md.